03.1 overview

Tools Overview

Tools allow BindAI agents to interact with the outside world.

Instead of relying solely on a language model, an agent can execute Python functions, query databases, call APIs, search documents, perform calculations, or integrate with third-party services.

Tools are one of the core building blocks of agentic applications.

---

What is a Tool?

A tool is an executable function that an AI model can call during an agent execution.

Typical examples include:

• searching the web
• querying a database
• reading files
• sending emails
• performing calculations
• interacting with business systems
• retrieving knowledge

The language model decides when a tool should be used, while BindAI executes it safely and returns the result back to the model.

---

Tool Execution Flow

User

↓

Agent

↓

Language Model

↓

Tool Request

↓

Tool Execution

↓

Tool Result

↓

Language Model

↓

Final Response

This process is automatic once tools are registered with an agent.

---

Why Use Tools?

Language models are limited to the information available in their context window and training data.

Tools allow agents to:

• access real-time information
• retrieve external knowledge
• execute business logic
• automate repetitive tasks
• interact with other applications
• perform deterministic operations

Without tools, agents can only generate text.

---

Creating a Tool

A tool is usually implemented as a Python function.

Example:

from bindai_tools import tool

@tool
def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny."

Once decorated, the function becomes available to agents.

---

Registering Tools

Tools are registered on an agent.

agent.tool(
    get_weather,
)

Multiple tools can be added.

agent.tool(search)

agent.tool(get_weather)

agent.tool(calculate)

The agent automatically exposes them to the language model.

---

Tool Discovery

During execution, BindAI converts registered tools into provider-compatible tool definitions.

The language model receives information such as:

• tool name
• description
• parameters
• parameter types

The model decides which tool should be called.

---

Automatic Tool Calling

Example conversation:

User

↓

"What is the weather in Tokyo?"

↓

Model requests get_weather()

↓

Tool executes

↓

Model receives result

↓

Final answer

No manual tool invocation is required.

---

Tool Parameters

Tool parameters are automatically exposed to the language model.

Example:

@tool
def search(
    query: str,
    limit: int = 5,
):
    ...

The model generates:

search(
    query="BindAI",
    limit=5
)

BindAI converts those arguments into Python values before execution.

---

Tool Results

Every tool returns a result object.

Example:

ToolResult(
    success=True,
    output="..."
)

The output is inserted back into the conversation so the model can continue reasoning.

---

Multiple Tool Calls

Agents may call several tools during one execution.

Search

↓

Database

↓

Calculator

↓

Final Answer

BindAI manages the execution loop automatically.

---

Tool Categories

Typical tool categories include:

• Search
• APIs
• Databases
• File System
• Email
• Calendar
• Knowledge Retrieval
• AI Services
• Business Systems

Applications can combine tools from multiple categories.

---

Shared Tools

Projects can expose shared tools.

project.add_tool(
    search_tool,
)

Multiple agents inside the project can then use the same implementation.

---

Tool Context

Every tool receives an execution context.

The context may include:

• variables
• workflow state
• metadata
• runtime information

This allows tools to access information beyond their input parameters.

---

Tool Validation

BindAI validates tool parameters before execution.

Benefits include:

• correct data types
• required parameters
• predictable execution
• provider-independent behavior

---

Tool Errors

If a tool fails, BindAI captures the error.

Example:

ToolResult(
    success=False,
    error="Database unavailable."
)

The language model can often recover by selecting another tool or responding appropriately.

---

Best Practices

• Design tools to perform one clear task.
• Keep tool descriptions concise and descriptive.
• Use explicit parameter names.
• Return deterministic outputs whenever possible.
• Handle failures gracefully.
• Avoid long-running blocking operations unless necessary.
• Reuse shared tools across agents.

---

Summary

Tools extend language models with real-world capabilities.

They allow agents to retrieve information, execute code, automate workflows, and interact with external systems while keeping the execution process consistent and provider-independent.